File picker for web apps

Your web apps can use a Microsoft OneDrive file picker to access a user's files on OneDrive.

In this article
Supported web browsers
Scenarios
Coding techniques
JSON format for folder and file lists
Related info

The Live SDK provides a Microsoft OneDrive file picker, a pre-built, consistent user interface that enables your JavaScript-based web apps to get either a folder location or a list of files from your user. Your web app can then use this info to upload or download files to and from the user's OneDrive storage location.

The OneDrive file picker is provided as part of the Live SDK JavaScript API (web) and therefore is available only for JavaScript-based web apps. For Windows Store apps, use a comparable user experience that Windows Store apps already provide for example, the various classes in the Windows.Storage.Pickers namespace. For all other app types, you'll have to provide your own user experience.

Supported web browsers

The following web browsers support the OneDrive file picker:

• Microsoft Internet Explorer, starting with version 8

• Mozilla Firefox, starting with version 10

• Apple Safari, starting with version 5.1

• Google Chrome, starting with version 17

Scenarios

There are two primary scenarios for using the OneDrive file picker. Your web app can either:

• Display the OneDrive file picker after the user has clicked a pre-built button with the OneDrive logo.

-or-

• Display the OneDrive file picker in response to the user interacting with your web app's UI (other than clicking the OneDrive button), or proactively without prior user interaction.

In both scenarios, the user must provide a list of files to upload or download from OneDrive to your web app. Using the file picker, you can provide a user interface that's presented and branded in a familiar way and also saves you coding time. Here's how it works.

1. When the OneDrive file picker appears, the user either:

   • Clicks the OneDrive folder to upload a file to.

   • Clicks the combination of folders or files or both to download, and then clicks Open.

2. The user then clicks Save.

3. The file picker returns the user-selected list of folders or files, or both, to your web app.

4. Your web app then uses this list to upload or download the files to or from OneDrive.

Coding techniques

After you decide which OneDrive file picker scenario you want to use, you can use the following coding techniques in your web app.

Display the OneDrive button by calling the WL.ui method

To display the OneDrive button, create a <div> tag and call the WL.ui method. Then follow these guidelines.

• The <div> tag must include an id attribute set to a unique value.

• If your web app is uploading a file, you also create a <form> tag and an <input> tag to get info about the file to upload.

  Note

  You can upload only one file at a time.

• The <form> tag must contain one and only one <input> tag.

  • This <input> tag must include name, type, and id attributes.

  • The value of the name and type attributes must be "file".

  • The id attribute can be set to any value, which is referred to by the WL.upload function's element parameter.

  • The user must provide info about the file to this <input> tag typically by clicking the <input> tag's accompanying Browse button and following the on-screen directions before clicking the OneDrive button; otherwise the call to the WL.upload method later will fail.

The WL.ui method accepts these parameters:

When the user clicks the OneDrive button, the file picker appears. After the user clicks Save or Open, the WL.ui method calls the function that's specified in its callback parameter. In the callback function, get the OneDrive upload location (to upload the user-selected file to) or the list of OneDrive download locations (to download the user-selected files from). Then either call the WL.upload method and supply the OneDrive upload location and info about the user-selected file, or call the WL.download method and supply the list of OneDrive download locations.

You can get the OneDrive upload location from the JavaScript Object Notation (JSON)-formatted data by getting the value of response.data.folders[0].id that's returned from the WL.ui method call. You can also get the list of OneDrive download locations from the JSON-formatted data by getting the response.data.folders and response.data.files arrays that are returned from the WL.ui method call. response is the name of the parameter that's specified in the WL.ui method's onSuccess parameter. For more info, see "JSON format for folder and file lists" later in this topic.

The WL.upload method accepts these parameters:

Parameter	Required/Optional	Description	Valid values	Default value
path	Required.	The unique OneDrive folder ID to upload the file to. Note You can upload only one file at a time.	A path or folder ID.	None.
file_name	Required.	The user-defined or app-defined name of the file to upload. Note Don't include the file name extension.	A file name, without the extension.	None.
element	Required.	The id attribute of the <input> tag.	Can be any unique value.	None.
overwrite	Optional.	Specifies whether to overwrite the file if a file of the same name exists.	true: Overwrites any existing file in the specified OneDrive folder with the same name. false: Prevents overwriting an existing file by failing if there is already a file with the same name in the specified OneDrive folder. rename: Uploads the file to the specified OneDrive folder even if that folder already has a file with the same name. Note When an file exists with the same name in the specified OneDrive folder, OneDrive chooses the uploaded file's name and ignores the value of the file_name parameter. The renamed file will start with the name of the existing file and will end with a sequential number. For example, if you specify rename and upload a file named textfile.txt to a folder that already contains a file with that name, the file will be stored in the OneDrive folder as textfile1.txt.	false

If the WL.upload method call is successful, you can use its then method's onSuccess parameter to report the success. Otherwise, you can use its then method's onError parameter to report an unsuccessful call. To check the progress of the WL.upload method call, you can use its then method's onProgress parameter; however, checking progress applies only to newer web browsers such as Internet Explorer 10.

The WL.download method accepts only one parameter:

• The required path parameter specifies the unique OneDrive file ID of the file to download.

If the WL.download method call is unsuccessful, you can use its then method's onError parameter to report the error. In this case, the WL.download doesn't support the onSuccess and onProgress parameters. If the WL.download method call is successful, the user experience for actually downloading the files will differ based on the type of web browser in use.

Here's a code example that shows how to upload a file by using a <form> tag, an <input> tag, a <div> tag, the WL.ui method, an app-defined callback function, and the WL.upload method.

<form>
    <input id="file" name="file" type="file" />
</form>
<div id="uploadFile_div">OneDrive save button to appear here</div>
WL.ui({
    name: "skydrivepicker",
    element: "uploadFile_div",
    mode: "save",
    onselected: onUploadFileCompleted,
    onerror: onUploadFileError
});

function onUploadFileCompleted(response) {
    WL.upload({
        path: response.data.folders[0].id,
        element: "file",
        overwrite: "rename"
    }).then(
        function (response) {
            document.getElementById("info").innerText = 
                "File uploaded."; 
        },
        function (responseFailed) {
            document.getElementById("info").innerText =
                "Error uploading file: " + responseFailed.error.message;
        }
    );
};

function onUploadFileError(response) {
    document.getElementById("info").innerText =
        "Error getting folder info: " + response.error.message; 
}

Here's a code example that shows how to use a <div> tag and the WL.ui method to display a list of files that the user wants to download.

<div id="downloadFile_div">OneDrive open button to appear here</div>

WL.ui({
    name: "skydrivepicker",
    element: "downloadFile_div",
    mode: "open",
    select: "multi",
    onselected: onDownloadFileCompleted,
    onerror: onDownloadFileError
});

function onDownloadFileCompleted(response) {
    var msg = "";
    // For each folder selected...
    if (response.data.folders.length > 0) {
        for (folder = 0; folder < response.data.folders.length; folder++) {
            // Use folder IDs to iterate through child folders and files as needed.
            msg += "\n" + response.data.folders[folder].id;
        }
    }
    // For each file selected...
    if (response.data.files.length > 0) {
        for (file = 0; file < response.data.files.length; file++) {
            // Use file IDs to iterate through files as needed.
            msg += "\n" + response.data.files[file].id;
        }
    }
    document.getElementById("info").innerText =
        "Selected folders/files:" + msg;
};

function onDownloadFileError(responseFailed) {
    document.getElementById("info").innerText =
        "Error getting folder/file info: " + responseFailed.error.message;
}

Display the file picker directly by calling the WL.fileDialog method

You can display the OneDrive file picker directly for example, in response to a button that is clicked (other than the OneDrive button). To do this, if your web app is uploading a file, you must create a <form> tag and an <input> tag to get info about the file to upload.

Then, whether your web app is uploading or downloading files, call the WL.fileDialog method.

For details about the <input> tag, see the previous section.

The WL.fileDialog method accepts the following parameters:

After the user clicks Save or Open, the WL.filedialog method calls its then method. If the then method's onSuccess parameter gets the OneDrive upload location (to upload the user-selected file to), call the WL.upload method and supply the OneDrive upload location and info about the user-selected file. If onSuccess gets the list of OneDrive download locations (to download the user-selected files from), call the WL.download method and supply the list of OneDrive download locations.

For details about getting either the OneDrive upload location or the list of OneDrive download locations, see the previous section.

For details about the WL.upload and WL.download methods, see the previous section.

Here's a code example that shows how to upload a file by using a <form> tag, an <input> tag, a <button> tag, the WL.fileDialog method, and the WL.upload method.

<form>
    <input id="file" name="file" type="file" />
</form>

<button onclick="uploadFile_fileDialog()">Save file with OneDrive file picker (calling WL.filedialog)</button>function uploadFile_fileDialog() {
    WL.fileDialog({
        mode: "save"
    }).then(
        function (response) {
            WL.upload({
                path: response.data.folders[0].id,
                element: "file",
                overwrite: "rename"
            }).then(
                function (response) {
                    document.getElementById("info").innerText =
                        "File uploaded.";
                },
                function (responseFailed) {
                    document.getElementById("info").innerText =
                        "Error uploading file: " + responseFailed.error.message;
                }
            );
        },
        function (responseFailed) {
            document.getElementById("info").innerText =
                "Error getting folder info: " + responseFailed.error.message;
        }
    );  
}

Here's a code example that shows how to use a <button> tag and the WL.fileDialog method to display a list of files that the user wants to download.

<button onclick="downloadFile_fileDialog()">Open file with OneDrive file picker (calling WL.filedialog)</button>
function downloadFile_fileDialog() {
    WL.fileDialog({
        mode: "open",
        select: "multi"
    }).then(
        function (response) {
            var msg = "";
            // For each folder selected...
            if (response.data.folders.length > 0) {
                for (folder = 0; folder < response.data.folders.length; folder++) {
                    // Use folder IDs to iterate through child folders and files as needed.
                    msg += "\n" + response.data.folders[folder].id;
                }
            }
            // For each file selected...
            if (response.data.files.length > 0) {
                for (file = 0; file < response.data.files.length; file++) {
                    // Use file IDs to iterate through files as needed.
                    msg += "\n" + response.data.files[file].id;                            
                }
            }
            document.getElementById("info").innerText =
                "Selected folders/files:" + msg;
        },
        function (responseFailed) {
            document.getElementById("info").innerText =
                "Error getting folder/file info: " + responseFailed.error.message;
        }
    );
}

Upload a file

To add contents for a file, photo, video, or audio, use code like this.

function uploadFile() {
    WL.login({
        scope: "wl.skydrive_update"
    }).then(
        function (response) {
            WL.upload({
                path: "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!170",
                element: "file",
                overwrite: "rename"
            }).then(
                function (response) {
                    document.getElementById("info").innerText =
                        "File uploaded.";
                },
                function (responseFailed) {
                    document.getElementById("info").innerText =
                        "Error uploading file: " + responseFailed.error.message;
                }
            );                    
        },
        function (responseFailed) {
            document.getElementById("info").innerText =
                "Error signing in: " + responseFailed.error.message;
        }
    );
}

Get a download link

To get a download link to a file, photo, video, or audio on OneDrive, use code like this.

function downloadFile() {
    WL.login({
        scope: "wl.skydrive"
    }).then(
        function (response) {
            WL.download({
                path: "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/content"
            }).then(
                function (response) {
                    // Will not be called for web apps.
                },
                function (responseFailed) {
                    document.getElementById("info").innerText =
                        "Error downloading file: " + responseFailed.error.message;
                }
            );
        },
        function (responseFailed) {
            document.getElementById("info").innerText =
                "Error signing in: " + responseFailed.error.message;
        }
    );
}

If the WL.ui or WL.fileDialog method call is successful, the method returns the resulting folder info (for upload or download requests) or file info (for download requests) to your app's code. The folder and file info is returned as a JSON-formatted object. Your app's code can then extract the folder ID and use it to call the WL.upload method (for upload requests), or to extract the folder IDs or file IDs, or both, and use them to call the WL.download method (for download requests).

For upload requests, the JSON-formatted object looks similar to this.

{
    "data": {
        "folders": [
            {
                "id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110",
                ... Additional info about this folder ...
            }
        ]
    }
}

Your app can then call the WL.upload method, specifying response.data.folders[0].id for the WL.upload method's path parameter. In the example just given, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter.

For download requests, the JSON-formatted object looks similar to this, depending on the number of folders or files, or both, that are selected.

{
    "data": {
        "folders": [
            {
                "id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110",
                ... If this folder was selected, additional info about this folder ...
            }, 
            {
                "id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!145",
                ... If this folder was selected, additional info about this folder ...
            }, 
            ... Info about additional folders that were selected, if any ...
        ],
        "files": [
            {
                "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131",
                ... If this file was selected, additional info about this file ...
            },
            {
                "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!144",
                ... If this file was selected, additional info about this file ...
            },
            {
                "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!152",
                ... If this file was selected, additional info about this file ...
            }, 
            ... Info about additional files that were selected, if any ...
        ]
    }
}

Your app can then call the WL.download method to download the files one at a time, specifying response.data.files[i].id for the WL.download method's path parameter. In the example just given, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter, and i is the name of the variable that's used to iterate through the lists of files. For code examples, see the previous sections.

To download files that are inside a folder, you first need to get the folder ID by specifying response.data.folders[i].id for the WL.api method's path parameter. In this example also, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter, and i is the name of the variable that's used to iterate through the list of folders. Your app can then use the response to iterate through the list of files in the folder and call the WL.download method on each file. For code examples, see the previous sections.

JSON format for folder and file lists

If the WL.ui or WL.fileDialog method call is successful, the method returns the resulting folder info (for upload or download requests) or file info (for download requests) to your app's code. The folder and file info is returned as a JSON-formatted object. Your app's code can then extract the folder ID and use it to call the WL.upload method (for upload requests), or to extract the folder IDs or file IDs, or both, and use them to call the WL.download method (for download requests).

For upload requests, the JSON-formatted object looks similar to this.

{
    "data": {
        "folders": [
            {
                "id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110",
                ... Additional info about this folder ...
            }
        ]
    }
}

Your app can then call the WL.upload method, specifying response.data.folders[0].id for the WL.upload method's path parameter. In the example just given, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter.

For download requests, the JSON-formatted object looks similar to this, depending on the number of folders or files, or both, that are selected.

{
    "data": {
        "folders": [
            {
                "id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110",
                ... If this folder was selected, additional info about this folder ...
            }, 
            {
                "id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!145",
                ... If this folder was selected, additional info about this folder ...
            }, 
            ... Info about additional folders that were selected, if any ...
        ],
        "files": [
            {
                "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131",
                ... If this file was selected, additional info about this file ...
            },
            {
                "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!144",
                ... If this file was selected, additional info about this file ...
            },
            {
                "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!152",
                ... If this file was selected, additional info about this file ...
            }, 
            ... Info about additional files that were selected, if any ...
        ]
    }
}

Your app can then call the WL.download method to download the files one at a time, specifying response.data.files[i].id for the WL.download method's path parameter. In the example just given, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter, and i is the name of the variable that's used to iterate through the lists of files. For code examples, see the previous sections.

To download files that are inside a folder, you first need to get the folder ID by specifying response.data.folders[i].id for the WL.api method's path parameter. In this example also, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter, and i is the name of the variable that's used to iterate through the list of folders. Your app can then use the response to iterate through the list of files in the folder and call the WL.download method on each file. For code examples, see the previous sections.

Related info

• The Live Interactive SDK, where you can experiment with the OneDrive file picker without writing any code

• WL.download (web)

• WL.fileDialog (web)

• WL.ui

• WL.upload